GitHub - ryaboy25/shiba-memory

Contribute to ryaboy25/shiba-memory development by creating an account on GitHub.

Summary

Shiba Memory is a TypeScript-based persistent memory layer for AI agents that combines semantic vector search with PostgreSQL full-text search, ACT-R-inspired activation, and tiered extraction. It exposes functionality through a CLI, HTTP gateway, Python SDK, and native hooks for Claude Code and the Hermes agent. The stack runs on PostgreSQL 16 with pgvector and is fully self-hosted.

What it is useful for

Shiba helps AI agents maintain durable, queryable memory across sessions and projects. Engineers using Claude Code get native hooks (SessionStart, PostToolUse, Stop, PreCompact, PostCompact) that inject prior context and capture new episodes. Hermes users get a plugin exposing shiba_recall, shiba_remember, and shiba_forget tools. Any other agent can hit the gateway directly with X-Shiba-Key auth — the README lists 17 REST endpoints covering remember/recall/forget, sessions, knowledge-graph linking, webhooks, and event queues. Hybrid retrieval fuses pgvector cosine similarity with websearch_to_tsquery, then layers ACT-R activation, confidence, project boosts (1.3x for same-project memories), and optional recency decay. Tiered extraction combines free regex pattern matching on phrases like "I prefer..." and "Don't..." with optional LLM summarization and correction detection.

How engineers can use it

The README documents a Docker-based setup with Docker, Node.js 18+, and an embedding provider as prerequisites:

git clone https://github.com/ryaboy25/shiba-memory.git
cd shiba-memory
cp .env.example .env
docker compose up -d postgres
cd cli && npm install && npm run build
node dist/index.js setup
node dist/index.js gateway start
curl http://localhost:18789/health

Three embedding providers are documented: Ollama (default, nomic-embed-text), a sentence-transformers FastAPI server (mxbai-embed-large-v1), or OpenAI's text-embedding-3-small. Vectors are stored as 16-bit halfvec HNSW indexes at 1024 dimensions. The Python SDK installs via pip install httpx or pip install -e . from sdks/python, exposing shiba.remember(...) and shiba.recall(...) methods.

Documented limitations worth noting: auto_link_memory only emits related links via embedding similarity, and contradiction detection uses embedding dissimilarity as a proxy — the README calls this "a flat adjacency list, not a full graph database — no multi-hop traversal or path finding." The HuggingFace TEI Docker image doesn't yet support Blackwell 12.x GPUs. On LongMemEval, multi-session retrieval scores 48.1% and implicit preferences 16.7%, both flagged as areas the project is actively improving.