{"id":47610633,"url":"https://github.com/giuliorossetti/ghostkg","last_synced_at":"2026-04-01T20:02:29.005Z","repository":{"id":336085748,"uuid":"1145980605","full_name":"GiulioRossetti/GhostKG","owner":"GiulioRossetti","description":"Dynamic Knowledge Graphs with Memory Decay for LLM Agents","archived":false,"fork":false,"pushed_at":"2026-02-03T07:30:12.000Z","size":692,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-03T07:31:59.588Z","etag":null,"topics":["fsrs","knowledge-graphs","llm-agents"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/GiulioRossetti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-30T13:17:46.000Z","updated_at":"2026-02-02T17:58:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/GiulioRossetti/GhostKG","commit_stats":null,"previous_names":["giuliorossetti/ghostkg"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/GiulioRossetti/GhostKG","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FGhostKG","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FGhostKG/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FGhostKG/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FGhostKG/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GiulioRossetti","download_url":"https://codeload.github.com/GiulioRossetti/GhostKG/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GiulioRossetti%2FGhostKG/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31291344,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["fsrs","knowledge-graphs","llm-agents"],"created_at":"2026-04-01T20:02:25.266Z","updated_at":"2026-04-01T20:02:28.997Z","avatar_url":"https://github.com/GiulioRossetti.png","language":"Python","readme":"# GhostKG - Dynamic Knowledge Graphs with Memory Decay for LLM Agents\n\n\u003cp align=\"center\"\u003e\n  \u003cem\u003eEnable your AI agents to remember, forget, and evolve their knowledge naturally\u003c/em\u003e\n\u003c/p\u003e\n\nGhostKG is a Python package that provides dynamic knowledge graph management for LLM agents with built-in memory decay using FSRS (Free Spaced Repetition Scheduler). It enables agents to maintain temporal, evolving knowledge bases that naturally forget information over time.\n\n## ✨ Features\n\n- 🧠 **Dynamic Knowledge Graphs**: Maintain structured knowledge as semantic triplets (subject-relation-object)\n- 📉 **Memory Decay**: FSRS-based spaced repetition models realistic memory retention and forgetting\n- ⏰ **Time-Aware**: Full support for temporal simulation and time-based queries\n- 💭 **Sentiment Tracking**: Emotional associations with knowledge (-1.0 to 1.0 scale)\n- 👥 **Multi-Agent Support**: Manage multiple agents with separate knowledge bases\n- 🔌 **Flexible Integration**: Use with any LLM (GPT-4, Claude, Ollama, etc.)\n- 🎯 **External API**: Decouple KG management from LLM logic for maximum flexibility\n- ⚡ **Fast Mode**: Optional GLiNER+TextBlob for quick extraction without LLM calls\n- 💾 **Database Flexibility**: Works with existing SQLite databases, preserving other tables\n- 📊 **Interactive Visualization**: Web-based visualization of knowledge graph evolution over time\n- 🗄️ **Multi-Database Support**: SQLite, PostgreSQL, and MySQL support with configurable connection pools\n\n## Installation\n\n### Using UV (Recommended)\n\n[UV](https://github.com/astral-sh/uv) is a fast Python package manager. Install it first:\n\n```bash\n# Install uv\ncurl -LsSf https://astral.sh/uv/install.sh | sh  # Unix/macOS\n# Or: pip install uv\n\n# Clone and install GhostKG\ngit clone https://github.com/GiulioRossetti/GhostKG.git\ncd GhostKG\n\n# Base installation (core features)\nuv pip install -e .\n\n# With LLM support (Ollama)\nuv pip install -e \".[llm]\"\n\n# With fast mode (GLiNER + TextBlob)\nuv pip install -e \".[fast]\"\n\n# With visualization\nuv pip install -e \".[viz]\"\n\n# With all features\nuv pip install -e \".[all]\"\n\n# For development\nuv pip install -e \".[dev]\"\n```\n\nSee [UV Setup Guide](docs/UV_SETUP.md) for detailed instructions.\n\n### Using pip\n\n```bash\n# From PyPI (when published)\npip install ghost_kg\n\n# From source\ngit clone https://github.com/GiulioRossetti/GhostKG.git\ncd GhostKG\npip install -e .\n\n# With optional features\npip install -e \".[llm]\"    # LLM support\npip install -e \".[fast]\"   # Fast mode\npip install -e \".[viz]\"    # Visualization server\npip install -e \".[all]\"    # All features\n```\n\n### Development Mode\n\nFor development without full package installation, use the `ghostkg_dev.py` script:\n\n```bash\n# Clone the repository\ngit clone https://github.com/GiulioRossetti/GhostKG.git\ncd GhostKG\n\n# Install minimal dependencies\npip install -r requirements/base.txt\npip install flask  # for visualization server\n\n# Use dev script (no package installation needed)\npython ghostkg_dev.py --help\npython ghostkg_dev.py export --database mydb.db --serve --browser\npython ghostkg_dev.py serve --json history.json --browser\n```\n\nAfter installing the package in editable mode (`pip install -e .`), use the regular `ghostkg` command instead.\n\n## Quick Start\n\n### Option 1: External Program API (Recommended)\n\nUse GhostKG as a library to manage agent KGs while keeping full control over LLM and business logic:\n\n```python\nfrom ghost_kg import AgentManager, Rating\nimport datetime\n\n# Initialize manager\nmanager = AgentManager(db_path=\"agents.db\")\n\n# Create agents\nalice = manager.create_agent(\"Alice\")\nbob = manager.create_agent(\"Bob\")\n\n# Set time\ncurrent_time = datetime.datetime.now(datetime.timezone.utc)\nmanager.set_agent_time(\"Alice\", current_time)\n\n# Add knowledge\nmanager.learn_triplet(\"Alice\", \"I\", \"support\", \"UBI\", rating=Rating.Easy, sentiment=0.8)\n\n# Process incoming content\ntriplets = [(\"Bob\", \"mentions\", \"automation\")]\nmanager.absorb_content(\"Alice\", \"Bob mentioned automation\", author=\"Bob\", triplets=triplets)\n\n# Get context for reply\ncontext = manager.get_context(\"Alice\", topic=\"UBI\")\n# Use context with your LLM to generate response\nresponse = your_llm.generate(context)\n\n# Update KG with response\nresponse_triplets = [(\"value\", \"economic security\", 0.7)]\nmanager.update_with_response(\"Alice\", response, triplets=response_triplets)\n```\n\nSee [API Documentation](docs/API.md) for complete details.\n\n### Option 2: Integrated LLM Approach\n\nUse GhostKG with built-in Ollama LLM integration:\n\n```python\nfrom ghost_kg import GhostAgent, CognitiveLoop\nimport datetime\n\n# Create agent\nagent = GhostAgent(\"Alice\", db_path=\"agent.db\")\nloop = CognitiveLoop(agent)\n\n# Set time\nagent.set_time(datetime.datetime.now(datetime.timezone.utc))\n\n# Agent reads and processes content\nloop.absorb(\"I think UBI is necessary.\", author=\"Bob\")\n\n# Agent generates reply\nresponse = loop.reply(\"UBI\", partner_name=\"Bob\")\n```\n\n### Option 3: Commercial LLM Providers\n\nUse OpenAI, Anthropic, Google, or Cohere with GhostKG:\n\n```python\nfrom ghost_kg import GhostAgent, CognitiveLoop\nfrom ghost_kg.llm import get_llm_service\nimport datetime\n\n# Create LLM service (OpenAI, Anthropic, Google, Cohere)\nllm_service = get_llm_service(\"openai\", \"gpt-4\")  # or \"anthropic\", \"google\", etc.\n\n# Create agent with commercial LLM\nagent = GhostAgent(\"Alice\", db_path=\"agent.db\", llm_service=llm_service)\nloop = CognitiveLoop(agent, model=\"gpt-4\")\n\n# Use like Option 2, but with GPT-4/Claude/etc.\nagent.set_time(datetime.datetime.now(datetime.timezone.utc))\nloop.absorb(\"I think UBI is necessary.\", author=\"Bob\")\nresponse = loop.reply(\"UBI\", partner_name=\"Bob\")\n```\n\n**📖 See [Usage Guide](docs/USAGE_GUIDE.md) for detailed examples of all usage modes and [LLM Providers](docs/LLM_PROVIDERS.md) for provider setup.**\n\n## Privacy \u0026 Storage Control\n\nGhostKG provides fine-grained control over what data is stored in logs:\n\n```python\n# Privacy-friendly: Store UUID instead of content (default)\nmanager = AgentManager(db_path=\"agents.db\", store_log_content=False)\n\n# Or: Store full content in logs\nmanager = AgentManager(db_path=\"agents.db\", store_log_content=True)\n```\n\n**Default behavior (store_log_content=False)**:\n- Content text is NOT stored in the database\n- A UUID is generated and stored instead\n- More privacy-friendly and reduces storage requirements\n\n**User-specified UUIDs**:\nYou can optionally provide your own UUID when content is not stored:\n\n```python\nimport uuid\n\ndb = KnowledgeDB(db_path=\"agents.db\", store_log_content=False)\n\n# Provide your own UUID for tracking\nmy_uuid = str(uuid.uuid4())\ndb.log_interaction(\n    agent=\"Alice\",\n    action=\"READ\",\n    content=\"sensitive content\",\n    annotations={},\n    content_uuid=my_uuid  # Use your own UUID\n)\n\n# Or let the system auto-generate one (default)\nauto_uuid = db.log_interaction(\n    agent=\"Bob\",\n    action=\"WRITE\",\n    content=\"another message\",\n    annotations={}\n)\n```\n\n**When to use store_log_content=True**:\n- When you need full audit trails of all interactions\n- For debugging and analysis purposes\n- When privacy is not a concern\n\n## Use Cases\n\n1. **Multi-Agent Simulations**: Model conversations between agents with evolving beliefs\n2. **Chatbot Memory**: Give chatbots persistent, time-aware memory that naturally decays\n3. **Research Assistants**: Track what an AI assistant knows and when it learned it\n4. **Game NPCs**: Create NPCs with realistic memory and knowledge evolution\n5. **Social Simulations**: Model opinion dynamics and information spread\n\n## Key Concepts\n\n### Knowledge Triplets\n\nKnowledge is stored as semantic triplets:\n- **Subject**: The source node (e.g., \"I\", \"Bob\", \"automation\")\n- **Relation**: The relationship (e.g., \"supports\", \"mentions\", \"affects\")\n- **Object**: The target node (e.g., \"UBI\", \"jobs\", \"economy\")\n\n### Memory Decay (FSRS)\n\nGhostKG uses FSRS v6 for realistic memory modeling:\n- **Stability**: How well information is retained\n- **Difficulty**: How hard it is to recall\n- **Retrievability**: Current probability of recall based on elapsed time\n- **Ratings**: Easy (4), Good (3), Hard (2), Again (1)\n\n### Time Management\n\nAll operations are time-aware:\n```python\nimport datetime\n\n# Set simulation time\ntime = datetime.datetime(2025, 1, 1, 9, 0, 0, tzinfo=datetime.timezone.utc)\nmanager.set_agent_time(\"Alice\", time)\n\n# Advance time\nfrom datetime import timedelta\ntime += timedelta(hours=1)\nmanager.set_agent_time(\"Alice\", time)\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────┐\n│   Your Application/LLM Integration   │\n│  (Business Logic, Text Generation)   │\n└──────────────┬──────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────┐\n│         GhostKG (AgentManager)      │\n│  ┌─────────────────────────────┐   │\n│  │   Agent Management          │   │\n│  │   • Create/retrieve agents  │   │\n│  │   • Update/query KGs        │   │\n│  └─────────────────────────────┘   │\n│  ┌─────────────────────────────┐   │\n│  │   Knowledge Graph Storage   │   │\n│  │   • Triplet management      │   │\n│  │   • Semantic filtering      │   │\n│  └─────────────────────────────┘   │\n│  ┌─────────────────────────────┐   │\n│  │   Memory System (FSRS)      │   │\n│  │   • Spaced repetition       │   │\n│  │   • Forgetting curves       │   │\n│  └─────────────────────────────┘   │\n└──────────────┬──────────────────────┘\n               │\n               ▼\n       ┌──────────────┐\n       │   SQLite DB  │\n       └──────────────┘\n```\n\n## 📊 Visualization\n\nGhostKG includes an interactive web-based visualization for exploring knowledge graph evolution:\n\n```bash\n# After installation\nghostkg export --database agent_memory.db --serve --browser\n\n# Development mode (without installation)\npython ghostkg_dev.py export --database agent_memory.db --serve --browser\n\n# Or export first, then serve\nghostkg export --database agent_memory.db --output history.json\nghostkg serve --json history.json --browser\n```\n\n# Or export first, then serve\n```bash\nghostkg export --database agent_memory.db --output history.json\nghostkg serve --json history.json --browser\n```\n\nFeatures:\n- **Interactive Force-Directed Graph**: D3.js visualization with zoom, pan, and drag\n- **Temporal Playback**: Step through agent interactions chronologically\n- **Multi-Agent View**: Switch between individual agents or consolidated view\n- **Memory Heatmap**: Node colors represent FSRS retrievability (forgetting curve)\n- **Playback Controls**: Play/pause, speed adjustment, timeline scrubbing\n\nSee [Visualization Guide](docs/VISUALIZATION.md) for detailed documentation.\n\n## 📚 Documentation\n\nComprehensive documentation is available in the `docs/` directory:\n\n### Getting Started\n- **[📖 Usage Guide](docs/USAGE_GUIDE.md)** - Complete guide to different usage modes (NEW!)\n  - Mode 1: External API (no internal LLM)\n  - Mode 2: Integrated LLM (Ollama self-hosted)\n  - Mode 3: Integrated LLM (OpenAI/Anthropic/etc.)\n  - Mode 4: Hybrid mode (external LLM + KG management)\n- **[🔌 LLM Providers](docs/LLM_PROVIDERS.md)** - Multi-provider LLM setup guide\n\n### Core Documentation\n- **[📑 Documentation Index](docs/index.md)** - Complete documentation overview with cross-references\n- **[🏗️ Architecture \u0026 Design](docs/ARCHITECTURE.md)** - System architecture and design philosophy\n- **[🔧 Core Components](docs/CORE_COMPONENTS.md)** - Detailed component specifications\n- **[📐 Algorithms \u0026 Formulas](docs/ALGORITHMS.md)** - Mathematical foundations and FSRS details\n- **[💾 Database Schema](docs/DATABASE_SCHEMA.md)** - Complete schema and query patterns\n- **[📊 Visualization Guide](docs/VISUALIZATION.md)** - Interactive visualization and CLI tools\n- **[🔌 API Reference](docs/API.md)** - External API documentation\n- **[⚡ Fast Mode Guide](docs/FAST_MODE_CONFIG.md)** - Fast vs LLM extraction modes\n- **[📚 Implementation Summaries](docs/summaries/)** - Detailed feature implementation histories\n\n### Quick Links\n- **[Getting Started](docs/index.md#for-new-users)** - New user guide\n- **[Integration Patterns](docs/ARCHITECTURE.md#integration-patterns)** - How to integrate with your app\n- **[Memory Decay Math](docs/ALGORITHMS.md#memory-decay-calculations)** - Understanding FSRS\n\n## 💡 Examples\n\nWorking code examples in the `examples/` directory:\n\n- **[multi_provider_llm.py](examples/multi_provider_llm.py)** - Using different LLM providers (Ollama, OpenAI, Anthropic, Google, Cohere) (NEW!)\n- **[use_case_example.py](examples/use_case_example.py)** - Two agents multi-round communication with configurable extraction modes\n- **[external_program.py](examples/external_program.py)** - Complete example of external program integration\n- **[hourly_simulation.py](examples/hourly_simulation.py)** - Time-based agent conversation simulation\n- **[export_history.py](examples/export_history.py)** - Export and analyze knowledge graph history\n\n## 📋 Requirements\n\n- Python \u003e= 3.8\n- networkx \u003e= 3.0\n- fsrs \u003e= 1.0.0\n- ollama \u003e= 0.1.6 (optional, for integrated LLM approach)\n- gliner (optional, for fast mode)\n- textblob (optional, for fast mode sentiment analysis)\n\n## 🔬 Research \u0026 Theory\n\nGhostKG is built on solid theoretical foundations:\n\n- **FSRS v6**: Advanced spaced repetition algorithm based on cognitive science\n- **Forgetting Curves**: Models natural memory decay over time\n- **Semantic Triplets**: Knowledge representation following RDF principles\n- **Temporal Knowledge Graphs**: Time-aware graph databases\n\nSee [Algorithms \u0026 Formulas](docs/ALGORITHMS.md) for mathematical details and references.\n\n## 📊 Performance\n\n- **Fast Mode**: Process ~100 messages/second (no LLM needed)\n- **LLM Mode**: Limited by LLM inference speed (~1-5 messages/second)\n- **Query Speed**: O(log n) lookups with proper indexing\n- **Storage**: ~150 bytes per triplet, ~100 bytes per entity\n\nSee [Database Schema](docs/DATABASE_SCHEMA.md#performance-considerations) for optimization details.\n\n## 🧪 Testing\n\nRun tests with pytest:\n\n```bash\npytest tests/\n```\n\nTest files:\n- `test_comprehensive.py` - Full workflow tests\n- `test_process_and_get_context.py` - API integration tests\n- `test_fast_mode_config.py` - Configuration validation\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## 🎓 Citation\n\nIf you use GhostKG in your research, please cite:\n\n```bibtex\n@software{ghostkg2025,\n  title={GhostKG: Dynamic Knowledge Graphs with Memory Decay for LLM Agents},\n  author={Rossetti, Giulio},\n  year={2025},\n  url={https://github.com/GiulioRossetti/GhostKG}\n}\n```\n\n## 🤝 Contributing\n\nContributions are welcome! Please:\n\n1. Check the [Architecture](docs/ARCHITECTURE.md) to understand the design\n2. Read [Core Components](docs/CORE_COMPONENTS.md) to understand the implementation\n3. Add tests for new features\n4. Update documentation\n5. Submit a Pull Request\n\n## 💬 Support\n\n- **Documentation**: [docs/index.md](docs/index.md)\n- **Issues**: [GitHub Issues](https://github.com/GiulioRossetti/GhostKG/issues)\n- **Examples**: [examples/](examples/) directory\n- **API Reference**: [docs/API.md](docs/API.md)\n\n## 🙏 Acknowledgments\n\nGhostKG builds upon:\n- **FSRS Algorithm** by Jarrett Ye and contributors\n- **Spaced Repetition Research** by cognitive scientists\n- **Knowledge Graph** and **RDF** standards\n- **SQLite** for reliable persistence\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuliorossetti%2Fghostkg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiuliorossetti%2Fghostkg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiuliorossetti%2Fghostkg/lists"}