Core Storage and Retrieval

\n\n| Module | Role |\n|--------|------|\n| `storage.py` | SQLite WAL engine, 16 tables, FTS5 indexing, `sqlite-vec` ANN search |\n| `embeddings.py` | Sentence-transformer encoding (`all-MiniLM-L6-v2`), batched operations |\n| `retrieval.py` | Four-signal fusion: vector similarity, FTS5 BM25, knowledge graph PPR, spreading activation |\n| `models.py` | Pydantic data models for the full type hierarchy |\n| `config.py` | Environment-based configuration with `ZIKKARON_` prefix |\n\n

\n\n

Memory Dynamics

\n\n| Module | Role |\n|--------|------|\n| `thermodynamics.py` | Heat, surprise, importance, emotional valence, temporal decay |\n| `reconsolidation.py` | Labile retrieval with three outcomes per Nader et al. (2000) |\n| `predictive_coding.py` | Write gate that filters redundancy via prediction error |\n| `engram.py` | Competitive slot allocation with CREB-like excitability |\n| `compression.py` | Rate-distortion optimal forgetting over three compression levels |\n| `staleness.py` | File-change watchdog via SHA-256 hash comparison |\n\n

\n\n

Consolidation and Organization

\n\n| Module | Role |\n|--------|------|\n| `consolidation.py` | Background astrocyte daemon for periodic consolidation |\n| `astrocyte_pool.py` | Domain-specialized worker processes for code, decisions, errors, deps |\n| `sleep_compute.py` | Dream replay, Louvain community detection, temporal compression |\n| `fractal.py` | Multi-scale memory tree with drill-down navigation |\n| `cls_store.py` | Complementary Learning Systems: fast episodic + slow semantic stores |\n\n

\n\n

Knowledge Structure

\n\n| Module | Role |\n|--------|------|\n| `knowledge_graph.py` | Typed entity-relationship graph with Personalized PageRank |\n| `causal_discovery.py` | PC algorithm for causal DAGs from coding session data |\n| `cognitive_map.py` | Successor Representation for navigation-based retrieval |\n| `narrative.py` | Autobiographical project story synthesis |\n| `curation.py` | Duplicate merging, contradiction detection, cross-reference linking |\n\n

\n\n

Frontier Capabilities

\n\n| Module | Role |\n|--------|------|\n| `hopfield.py` | Modern continuous Hopfield networks (Ramsauer et al., 2021) |\n| `hdc_encoder.py` | Hyperdimensional Computing in 10,000-dimensional bipolar space |\n| `metacognition.py` | Self-assessment of knowledge coverage and gap detection |\n| `rules_engine.py` | Hard and soft neuro-symbolic constraints |\n| `crdt_sync.py` | Multi-agent memory sharing via CRDTs |\n| `prospective.py` | Future-oriented triggers on directory, keyword, entity, or time |\n| `sensory_buffer.py` | Episodic capture buffer for raw session content |\n| `restoration.py` | Hippocampal Replay engine for context compaction resilience |\n| `seed.py` | Project scanning and foundational memory bootstrapping |\n\n

\n\n## Advanced setup\n\n### From source\n\n```bash\ngit clone https://github.com/amanhij/Zikkaron.git\ncd Zikkaron\npip install -e .\n```\n\n### SSE transport\n\nRun as a persistent background server instead of stdio:\n\n```bash\nzikkaron --transport sse\n```\n\nThen point Claude Code at the URL:\n\n```json\n{\n \"mcpServers\": {\n \"zikkaron\": {\n \"type\": \"sse\",\n \"url\": \"http://127.0.0.1:8742/sse\"\n }\n }\n}\n```\n\nDefault port is `8742`. Override with `--port`. Database defaults to `~/.zikkaron/memory.db`, override with `--db-path`.\n\n## Configuration\n\nAll settings use the `ZIKKARON_` environment variable prefix:\n\n| Variable | Default | What it controls |\n|----------|---------|-----------------|\n| `ZIKKARON_PORT` | `8742` | Server port |\n| `ZIKKARON_DB_PATH` | `~/.zikkaron/memory.db` | Database location |\n| `ZIKKARON_EMBEDDING_MODEL` | `all-MiniLM-L6-v2` | Sentence-transformer model |\n| `ZIKKARON_DECAY_FACTOR` | `0.95` | Heat decay per consolidation cycle |\n| `ZIKKARON_COLD_THRESHOLD` | `0.05` | Heat below which memories become archival candidates |\n| `ZIKKARON_WRITE_GATE_THRESHOLD` | `0.4` | Minimum surprisal to pass the write gate |\n| `ZIKKARON_HOPFIELD_BETA` | `8.0` | Hopfield network sharpness |\n| `ZIKKARON_SR_DISCOUNT` | `0.9` | Successor representation discount factor |\n| `ZIKKARON_COGNITIVE_LOAD_LIMIT` | `4` | Active context chunk limit (Cowan's 4 +/- 1) |\n\nFull list in `zikkaron/config.py`.\n\n## Testing\n\n```bash\npython -m pytest zikkaron/tests/ -x -q\n```\n\n998 tests across 34 test files covering every subsystem.\n\n## References\n\n

The papers and books behind the implementation

\n\nRamsauer et al. \"Hopfield Networks is All You Need\" (ICLR 2021, arXiv:2008.02217)\n\nNader, Schafe, LeDoux. \"Fear memories require protein synthesis in the amygdala for reconsolidation after retrieval\" (Nature 406, 2000)\n\nOsan, Tort, Bhatt, Amaral. \"Three outcomes of reconsolidation\" (PLoS ONE, 2011)\n\nMcClelland, McNaughton, O'Reilly. \"Why there are complementary learning systems in the hippocampus and neocortex\" (Psychological Review 102, 1995)\n\nSun et al. \"Organizing memories for generalization in complementary learning systems\" (Nature Neuroscience 26, 2023)\n\nStachenfeld, Botvinick, Gershman. \"The hippocampus as a predictive map\" (Nature Neuroscience 20, 2017)\n\nWhittington et al. \"The Tolman-Eichenbaum Machine\" (Cell 183, 2020)\n\nSpirtes, Glymour, Scheines. *Causation, Prediction, and Search* (MIT Press, 2000)\n\nKanerva. *Sparse Distributed Memory* (MIT Press, 1988)\n\nFrady, Kleyko, Sommer. \"Variable Binding for Sparse Distributed Representations\" (IEEE TNNLS, 2022)\n\nToth et al. \"Optimal forgetting via rate-distortion theory\" (PLoS Computational Biology, 2020)\n\nJosselyn, Frankland. \"Memory allocation: mechanisms and function\" (Annual Review Neuroscience 41, 2018)\n\nRashid et al. \"Competition between engrams influences fear memory formation and recall\" (Science 353, 2016)\n\nZhou et al. \"MetaRAG: Metacognitive Retrieval-Augmented Generation\" (ACM Web, 2024)\n\n

\n\n## License\n\nMIT\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_109":110,"_111":112,"_113":114,"_115":116,"_117":118,"_119":120},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102,103,104,105,106,107,108],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","agent-memory","artificial-intelligence","causal-inference","claude","claude-code","cognitive-architecture","complementary-learning-systems","hopfield-networks","knowledge-graph","llm-tools","memory","neuroscience","persistent-memory","predictive-coding","retrieval-augmented-generation","topics",[94,95,96,97,98,99,100,101,102,103,125,126,104,127,105,106,107,108,128,129],"license","MIT","language","Python","registryName","io.github.amanhij/zikkaron","homepage","https://zikkaron-frontend.vercel.app","packages",[121],{"_122":123,"_124":21,"_71":72},"registryType","pypi","identifier","mcp","mcp-server","model-context-protocol","sqlite","vector-search","ENV",{"_132":133,"_134":135,"_136":137},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]