{"id":50452989,"url":"https://github.com/ajayvardhanreddy/agent-memory-service","last_synced_at":"2026-06-01T01:01:14.004Z","repository":{"id":350751114,"uuid":"1208126827","full_name":"Ajayvardhanreddy/agent-memory-service","owner":"Ajayvardhanreddy","description":"Agent Memory Service — session memory and activity stream for AI agents, built on a distributed KV store","archived":false,"fork":false,"pushed_at":"2026-05-29T06:13:28.000Z","size":77,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T07:32:06.193Z","etag":null,"topics":["agent-memory","agents","ai-agents","ai-infrastructure","distributed-systems","fastapi","llm","llm-infrastructure","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Ajayvardhanreddy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-11T21:19:26.000Z","updated_at":"2026-05-29T06:13:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"7729af6a-949c-41c6-9633-ee9d17a2908e","html_url":"https://github.com/Ajayvardhanreddy/agent-memory-service","commit_stats":null,"previous_names":["ajayvardhanreddy/agent-memory-service"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/Ajayvardhanreddy/agent-memory-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajayvardhanreddy%2Fagent-memory-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajayvardhanreddy%2Fagent-memory-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajayvardhanreddy%2Fagent-memory-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajayvardhanreddy%2Fagent-memory-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Ajayvardhanreddy","download_url":"https://codeload.github.com/Ajayvardhanreddy/agent-memory-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Ajayvardhanreddy%2Fagent-memory-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33755369,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent-memory","agents","ai-agents","ai-infrastructure","distributed-systems","fastapi","llm","llm-infrastructure","python"],"created_at":"2026-06-01T01:00:34.751Z","updated_at":"2026-06-01T01:01:13.980Z","avatar_url":"https://github.com/Ajayvardhanreddy.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Agent Memory Service\n\nSession memory and activity stream for AI agents, built on a [distributed KV store](https://github.com/Ajayvardhanreddy/distributed-kv-store).\n\n```\n   AI Agent\n      │\n      │ HTTP\n      ▼\n   Agent Memory Service (:8080)\n   MemoryService │ ActivityStream │ CleanupJob\n      │\n      │ HTTP (httpx, round-robin, failover)\n      ▼\n   Distributed KV Store Cluster\n   node-0:8000  node-1:8001  node-2:8002\n      │              │              │\n      WAL           WAL           WAL\n```\n\n## Why a custom KV store?\n\nThis service is built on [distributed-kv-store](https://github.com/Ajayvardhanreddy/distributed-kv-store) rather than Redis or Postgres to demonstrate the full infrastructure stack — from consistent hashing and WAL-based replication to application-layer session management. The architectural separation (application layer on top of infrastructure) mirrors how production AI companies build on their own storage systems. The KV store provides versioned keys, synchronous replication, and automatic failover — exactly the primitives a memory service needs.\n\n## API Reference\n\n| Method | Path | Description | Returns |\n|--------|------|-------------|---------|\n| `POST` | `/memory/{agent_id}/{session_id}/append` | Append a message to a session | `SessionResponse` |\n| `GET` | `/memory/{agent_id}/sessions` | List all sessions for an agent | `SessionListResponse` |\n| `GET` | `/memory/{agent_id}/{session_id}` | Get full session with all messages | `SessionResponse` |\n| `GET` | `/memory/{agent_id}/{session_id}/window?last_n=10` | Get last N messages | `WindowResponse` |\n| `DELETE` | `/memory/{agent_id}/{session_id}` | Delete a session | `{\"message\": \"deleted\"}` |\n| `GET` | `/stream/{agent_id}?limit=50` | Get activity stream events | `StreamResponse` |\n| `GET` | `/stream/{agent_id}/filter?action=append\u0026limit=20` | Filter events by action type | `StreamResponse` |\n| `GET` | `/health` | Service and KV cluster health | Health status |\n| `GET` | `/` | Service info and endpoint list | Service metadata |\n\n## Running Locally\n\n**1. Start the KV cluster:**\n\n```bash\ngit clone https://github.com/Ajayvardhanreddy/distributed-kv-store.git\ncd distributed-kv-store\ndocker-compose up -d\n```\n\n**2. Start the memory service:**\n\n```bash\ncd agent-memory-service\npip install -r requirements.txt\nuvicorn app.main:app --port 8080\n```\n\n**3. Test it:**\n\n```bash\n# Append a message\ncurl -X POST http://localhost:8080/memory/agent1/session1/append \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"role\": \"user\", \"content\": \"Hello, I need help with my order.\"}'\n\n# Get the session\ncurl http://localhost:8080/memory/agent1/session1\n\n# Get sliding window (last 5 messages)\ncurl http://localhost:8080/memory/agent1/session1/window?last_n=5\n\n# Check health\ncurl http://localhost:8080/health\n```\n\n## Running the Demo\n\nThe demo script runs a fully automated 6-scene demonstration that proves versioned memory, sliding windows, fault tolerance, and activity streaming.\n\n```bash\npython demo/demo.py\n```\n\nExpected output: 6 scenes showing version-consistent appends, sliding window retrieval, node failure survival, writes with a node down, WAL-based rejoin sync, and activity stream audit trail. Completes in under 60 seconds.\n\n## Running with Docker\n\n```bash\n# Make sure the KV cluster is running first\ndocker-compose up --build\n```\n\n## Tests\n\n```bash\npytest tests/ -v --tb=short\n```\n\n26 unit tests across 3 test files covering the KV client, memory service, and activity stream.\n\n## Key Design Decisions\n\n### Optimistic concurrency with version counters\n\nEvery session write reads the current version N, appends the message, then writes and verifies the returned version is N+1. If another writer raced us, the version will be higher — we retry up to 3 times with a short backoff. This avoids distributed locks while guaranteeing no lost updates.\n\n### In-memory activity stream index\n\nEvents are stored in the KV store but indexed in memory (`dict[agent_id, list[kv_key]]`). This means the index is empty after a service restart — events from before the last restart exist in the KV store but cannot be queried until new events rebuild the index. **Production alternative:** Redis sorted sets keyed by timestamp, or a dedicated time-series store like TimescaleDB.\n\n### TTL via background registry\n\nThe KV store has no TTL support and no scan endpoint. The cleanup job maintains a set of known session keys and periodically checks each one's `updated_at` timestamp. Sessions created before a service restart are not tracked until they are accessed again. **Production alternative:** Store session keys in a Redis SET or maintain a secondary index key in the KV store.\n\n### Session index via secondary index key\n\nThe KV store has no scan endpoint, so session listing is implemented with a secondary index key `index:{agent_id}` that holds the list of known session IDs for that agent. This key is updated on every session creation and deletion using the same optimistic concurrency pattern as session writes. **Production alternative:** Redis SET or a metadata table in Postgres for larger scale.\n\n## Known Limitations\n\n| Limitation | Impact | Production Solution |\n|------------|--------|-------------------|\n| Index only tracks sessions created after first deploy | Sessions that existed before the index key was introduced are not listed | Backfill job, or use activity stream events to rebuild |\n| In-memory stream index | Empty after restart; old events not queryable | Redis sorted sets or TimescaleDB |\n| Registry-based TTL | Missed sessions from before restart | Redis SET or KV-stored index key |\n| Single-service deployment | No horizontal scaling of memory service | Stateless design already supports it — just add a load balancer |\n| No authentication | Open API endpoints | API key middleware or OAuth2 |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajayvardhanreddy%2Fagent-memory-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fajayvardhanreddy%2Fagent-memory-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fajayvardhanreddy%2Fagent-memory-service/lists"}