{"_id":"@darkrei08/ai-memory-kit","name":"@darkrei08/ai-memory-kit","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@darkrei08/ai-memory-kit","version":"0.1.0","description":"Machine-independent, repository-centric memory for AI coding agents (project-memory skill + aimem CLI + Engram/gga integration).","type":"module","license":"MIT","author":{"name":"darkrei08"},"homepage":"https://github.com/darkrei08/ai-memory-kit#readme","repository":{"type":"git","url":"git+https://github.com/darkrei08/ai-memory-kit.git"},"bugs":{"url":"https://github.com/darkrei08/ai-memory-kit/issues"},"bin":{"ai-memory-kit":"bin/ai-memory-kit.mjs","aimem":"bin/ai-memory-kit.mjs"},"engines":{"node":">=16"},"keywords":["ai","memory","agent","engram","gga","gentle-ai","persistent-memory","project-memory","repository-memory","context","adr","pi","claude","cursor","codex"],"scripts":{"test":"sh -n bin/aimem && node --check bin/ai-memory-kit.mjs"},"gitHead":"e34913bc505beaee0f5cb2a49f09fb07352575eb","_id":"@darkrei08/ai-memory-kit@0.1.0","_nodeVersion":"26.7.0","_npmVersion":"12.0.2","dist":{"integrity":"sha512-PBQOOU9YTqqDXFbCRWkJMOgKsNjqT/iXBXOAybe1Pl30qpUedFdtTo6cjW1wCnKlq+EBR840KUFgPMF7CRjqng==","shasum":"a85417123357f5292adb6b789a9bff3fe13cb8cb","tarball":"https://registry.npmjs.org/@darkrei08/ai-memory-kit/-/ai-memory-kit-0.1.0.tgz","fileCount":26,"unpackedSize":50886,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDVDOdJ1irp0uLp3T8C7kymrHufbd3fc+1CsqFbXHd76AIhAMHaxEh3C0abMldoMCY9ZDY50kJzqqs+bZqDj3L6Q73S"}]},"_npmUser":{"name":"darkrei08","email":"darkrei08@gmail.com"},"directories":{},"maintainers":[{"name":"darkrei08","email":"darkrei08@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/ai-memory-kit_0.1.0_1789143043049_0.18745667683154976"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-11T16:10:42.858Z","0.1.0":"2026-09-11T16:10:43.186Z","modified":"2026-09-11T16:10:43.374Z"},"maintainers":[{"name":"darkrei08","email":"darkrei08@gmail.com"}],"description":"Machine-independent, repository-centric memory for AI coding agents (project-memory skill + aimem CLI + Engram/gga integration).","homepage":"https://github.com/darkrei08/ai-memory-kit#readme","keywords":["ai","memory","agent","engram","gga","gentle-ai","persistent-memory","project-memory","repository-memory","context","adr","pi","claude","cursor","codex"],"repository":{"type":"git","url":"git+https://github.com/darkrei08/ai-memory-kit.git"},"author":{"name":"darkrei08"},"bugs":{"url":"https://github.com/darkrei08/ai-memory-kit/issues"},"license":"MIT","readme":"# ai-memory-kit\r\n\r\n**Machine-independent, repository-centric memory for AI coding agents.**\r\n\r\nClone a repo on any machine, run one command, and your agent already knows the\r\narchitecture, conventions, decisions, past problems, reviews, and open work —\r\nwithout you rebuilding the context by hand.\r\n\r\nThe repository is the entry point. Durable memory is **versioned inside the repo**;\r\na local memory engine ([Engram](https://github.com/Gentleman-Programming/engram))\r\nis only a fast cache that is **rehydrated from the repo**, never the source of truth.\r\nNo servers, no accounts, no lock-in.\r\n\r\n```\r\nnew machine → npx @darkrei08/setup-ai → git clone <project> → aimem bootstrap → agent ready\r\n```\r\n\r\n## Why\r\n\r\nLocal agent memory (an Engram SQLite DB, a code index, caches) lives in `~` and\r\ndies with the machine. If context is only there, a reinstall or a new laptop wipes\r\nit. This kit makes the **repository** carry its own memory so any machine or agent\r\ncan reconstruct it deterministically.\r\n\r\n## What it is (grounded in real tools)\r\n\r\nThree artifacts, nothing more:\r\n\r\n| Artifact | Purpose |\r\n| --- | --- |\r\n| `skills/project-memory/SKILL.md` | Global directive teaching an agent the read/update memory protocol. Installed like any skill (`npx skills add …`). |\r\n| `bin/aimem` | POSIX-sh CLI (zero deps) to scaffold, bootstrap, and sync per-project memory. |\r\n| `templates/` | The versioned `.ai/` memory scaffold copied into a project by `aimem init`. |\r\n\r\nIt composes existing tools **only via their real, verified commands**:\r\n\r\n- **Engram** (`engram`) — `sync` / `sync --import` move memory as committed chunks\r\n  over git; `save`, `search`, `context`, `conflicts scan`, `projects consolidate`,\r\n  `doctor`, `export`/`import`. Local DB in `~/.engram` (ephemeral).\r\n- **GGA** (`gga`, Gentleman Guardian Angel) — pre-commit AI review reading `.gga` +\r\n  `AGENTS.md`. Review outcomes are captured into `.ai/reviews/`.\r\n- **Gentle-AI** (`gentle-ai`) — the ecosystem configurator that installs the harness\r\n  and MCP servers (including Engram) per agent.\r\n\r\nIt never invents tool behavior and never edits a host project's build pillars.\r\n\r\n## Memory layers\r\n\r\nThe design separates four layers explicitly:\r\n\r\n1. **Global directives** — the `project-memory` skill + agent config. Installed with\r\n   your setup; valid for every project. Machine-level.\r\n2. **Repository-persistent memory** — versioned, authoritative:\r\n   - `.ai/*.md` — human source of truth (curated, diffable).\r\n   - `.engram/chunks/` — machine-readable Engram cache (committed).\r\n3. **Local / ephemeral** — `~/.engram/engram.db`, `.atl/`, `.codegraph/`, `gga` cache.\r\n   Regenerable; **never required** to reconstruct context; git-ignored.\r\n4. **Shared / synced** — the same `.engram/chunks/` moved by **git** (default), or an\r\n   opt-in Engram **cloud** endpoint.\r\n\r\nThe invariant: **nothing required to reconstruct context depends on un-versioned\r\nlocal state.** Anything that must not be committed (secrets, indexes) is declared in\r\n`.ai/manifest.yml` and regenerated at bootstrap via `.ai/bootstrap.d/*.sh`.\r\n\r\n## Repository layout it creates (`aimem init`)\r\n\r\n```\r\n<your-project>/\r\n├── AGENTS.md                 # entry point; points the agent at .ai/ (added if absent)\r\n├── .gga                      # gga review config (added if absent)\r\n├── .gitignore                # merged: ignore .atl/ .codegraph/ *.local (NOT .engram/)\r\n├── .ai/                      # human source of truth (versioned)\r\n│   ├── CONTEXT.md            # architecture & structure\r\n│   ├── conventions.md        # conventions adopted\r\n│   ├── directives.md         # repo-specific operator directives\r\n│   ├── decisions/            # ADRs: NNNN-title.md (decision + rationale, supersede chain)\r\n│   ├── reviews/              # captured review outcomes\r\n│   ├── changelog.md          # notable changes & refactors\r\n│   ├── problems.md           # problems encountered + solutions\r\n│   ├── todo.md               # TODO / tech debt / open work\r\n│   ├── manifest.yml          # declarative bootstrap manifest (no secrets)\r\n│   └── bootstrap.d/          # executable regenerators for local, non-committed state\r\n└── .engram/\r\n    └── chunks/               # machine-readable Engram cache (versioned)\r\n```\r\n\r\n## Install\r\n\r\nAs a module (the way skills and other modules are called):\r\n\r\n```bash\r\n# the CLI + templates + skill, via the standalone installer\r\ncurl -fsSL https://raw.githubusercontent.com/darkrei08/ai-memory-kit/main/install.sh | bash\r\n\r\n# or just the skill into a specific agent, via the skills tool\r\nnpx skills add darkrei08/ai-memory-kit --skill project-memory --global --agent pi --copy --yes\r\n\r\n# via npm — runs the same aimem CLI; requires a POSIX shell (Git Bash/WSL on Windows)\r\nnpx @darkrei08/ai-memory-kit init\r\n# or install the command globally\r\nnpm i -g @darkrei08/ai-memory-kit\r\n```\r\n\r\nThe npm package bundles the `.ai/` templates and runs the same `aimem` CLI through\r\na zero-dependency Node launcher, so `npx @darkrei08/ai-memory-kit <cmd>` behaves\r\nidentically to the installed `aimem <cmd>`.\r\n\r\nWindows: `irm https://raw.githubusercontent.com/darkrei08/ai-memory-kit/main/install.ps1 | iex`\r\n\r\nFrom a clone: `./install.sh` (see `./install.sh --list`).\r\n\r\n## Use\r\n\r\n```bash\r\ncd my-project\r\naimem init            # scaffold .ai/ + .engram/ (idempotent; never clobbers your text)\r\n# ... edit .ai/CONTEXT.md, conventions.md, directives.md ...\r\ngit add .ai .engram AGENTS.md .gga .gitignore && git commit\r\n\r\n# during work, record memory to Markdown + Engram, then stage chunks:\r\naimem save \"Chose Postgres over Mongo\" \"Relational integrity + reporting needs. See ADR 0007.\" decision\r\naimem sync            # exports new memories to .engram/chunks/ to commit\r\n\r\n# on a fresh clone / new machine:\r\naimem bootstrap       # rehydrate Engram from chunks, regenerate local state, print context\r\naimem status          # tools, project, layout, sync status\r\naimem doctor          # deeper diagnostics incl. a secret smell-test\r\n```\r\n\r\n## Documentation\r\n\r\n- [docs/architecture.md](docs/architecture.md) — components, responsibilities, data flow\r\n- [docs/bootstrap.md](docs/bootstrap.md) — new-machine & new-project processes\r\n- [docs/usage-examples.md](docs/usage-examples.md) — concrete end-to-end examples\r\n- [docs/security-privacy.md](docs/security-privacy.md) — secrets, redaction, cloud opt-in\r\n- [docs/conflicts-and-staleness.md](docs/conflicts-and-staleness.md) — dedup, conflicts, stale data\r\n\r\n## Design principles\r\n\r\nSimplicity · portability · idempotence · automation · **no lock-in**. Declarative\r\nversioned files + a deterministic bootstrap beat standing infrastructure.\r\n\r\n## License\r\n\r\nMIT. Installed tools keep their own licenses.\r\n","readmeFilename":"README.md","_rev":"1-9734f46fc9c21c91d6766dd367414f85"}