# Greplica: persistent engineering memory for Codex and Claude Code

> Greplica stores repo context in local SQLite and lets a coding agent query it before exploring. It targets repeated context-building across sessions, and ships a managed mode for shared team memory.

**Autoloops/greplica** — Persistent, searchable engineering memory for AI coding agents. Saves ~50% tokens and ~30% time while planning

- Repository: https://github.com/Autoloops/greplica
- Website: https://autoloops.ai/greplica
- Stars: 436 · Forks: 74
- Language: TypeScript
- License: MIT
- Published: 2026-09-20 · Updated: 2026-09-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/autoloops-greplica

## The repeated-context problem Greplica is built around

The README opens with a specific complaint: a coding agent spends minutes grepping around on a complex task because it is re-learning context it already had in a previous session. The stated cost is tokens and time spent rebuilding that context, plus facts the agent still misses.

The intended user is someone running an agent such as Codex or Claude Code against a repository they return to often. Greplica explores repo structure, code and session transcripts, then exposes the result as memory the agent can query before it starts exploring. That ordering matters: the value only appears if the agent asks first. An agent that ignores the memory and greps anyway gets no benefit, and the README's own framing is that most users should not install Greplica by hand but paste an install prompt into their coding agent.

This is not a general documentation generator. It is a cache for engineering context, and like any cache it is only worth its maintenance cost when the same questions recur.

## Local SQLite versus managed memory: how the two modes differ

Greplica has two storage shapes. Local mode stays on the machine with no telemetry, according to the README. Managed mode connects an authorized repository to shared team memory, so contributors on different clones and forks can query the same repository memory. Managed mode requires Greplica 0.2.0 or later and access to a managed Greplica server.

The split is visible in what each side stores. Managed graph data stays on the server. Local SQLite keeps only the repository binding, role cache, hook policy and runtime session metadata. So even in managed mode, the local database is an index of relationships, not a copy of the graph.

Retrieval defaults are worth reading closely. Managed retrieval defaults to canonical main plus your own persistent working memory, and other contributors are added explicitly:

```bash
npm install -g greplica@latest
cd /path/to/your/repository-or-fork
greplica login --api-url https://memory.autoloops.ai
greplica install --mode managed --platform codex
greplica repo status
greplica graph context "What should I know before changing this subsystem?"
```

To pull in another person's drafts, the README shows `--with-working alice --with-working bob` on the context command. Roles are coarse: organization admins and members inherit read access to every organization repository, guests read only explicitly granted repositories, a contributor writes proposals to a personal working scope, and memory_admin additionally manages repository memory access.

## Installing Greplica and running a first query

Greplica requires Node.js 22 to 26, and package.json narrows that to `>=22.0.0 <27.0.0` with a preinstall check that fails on other versions. The README's recommended path is not a manual install. It is a prompt you paste into your coding agent from inside the repository you want remembered:

```txt
Install Greplica for this repo using https://raw.githubusercontent.com/Autoloops/greplica/refs/heads/main/docs/agent-install-prompt.md.
```

That prompt runs a short setup questionnaire, installs Greplica in local or managed mode, and either creates the first local context or connects to existing shared memory. If you prefer to drive it yourself, the package is `greplica` on npm and the binary is `greplica`.

Once memory exists, the README's visualization command opens the current memory in a browser:

```bash
greplica graph view
```

What you should see is a graph view of the stored memory. The repository also ships offline-browser checks for that view, which suggests the view is expected to work without a live server, though the README does not spell out the offline behaviour. For a first real use, the managed example above is the clearest: install with `--platform codex`, then ask `greplica graph context` a question about a subsystem you already understand, and judge the answer against what you know.

## What the reconcile workflow actually enforces

Managed repositories reconcile Memory PRs against exact default-branch code through a reusable GitHub workflow. The README is unusually specific about the guarantees, which is where the design gets interesting and also where the operational burden lands.

The workflow checks out `merge-sha` with full history, installs an immutable Greplica Action revision, proves that each code PR's recorded merge commit is contained in that exact checkout, audits every eligible Memory PR's version-keyed claim and component anchors including code drift from stored baselines, and attests through GitHub OIDC. It does not use a repository or model secret. Pin the reusable workflow to a full commit SHA, the README says, not a branch or movable tag:

```yaml
name: Greplica memory

on:
  push:
    branches: [main] # Replace with the repository's default branch.
  schedule:
    - cron: "17 * * * *"
  workflow_dispatch:

permissions:
  contents: read
  id-token: write
```

The push trigger reconciles immediately after default-branch updates; the hourly schedule retries unmatched and stalled work without a human memory-admin step. Repair evidence, when a compatible managed server requests it, is a deterministic packet bound to that exact SHA. It reads only the anchors named by the selected claim and component versions, never a repository-wide content scan, and limits the packet to 128 anchors, 4 KiB and 80 lines per snippet, and 64 KiB of snippets total. Snippets can come only from regular blobs tracked at the attested commit, with checkout bytes verified against that blob. Traversal is rejected; ignored or untracked files, symlinks, submodules, sensitive paths, binary or oversized files, and high-confidence credential content appear only as non-content omissions. Omissions become explicit `unverifiable` failures rather than independently appearing clean, and managed repair may use only `resolved` or `file_only` entries whose transmitted snippet hash and current anchor fingerprint are present and valid.

That is a lot of machinery, and it is the honest cost of the feature. The README notes that older servers retain the prior attestation shape, so mixed-version fleets behave differently depending on the server.

## Where Greplica is the wrong tool

The first limitation is the one the README itself concedes: most users should not install it by hand. If your workflow does not give a coding agent permission to run install commands, the primary onboarding path is closed to you.

The second is scope. Managed memory requires a managed Greplica server. The README documents `https://memory.autoloops.ai` and a login flow, but it does not document running your own managed server, so a team that wants shared memory without that dependency has no path described here. Local mode avoids the server, but local memory is per repository binding and does not give contributors on different clones the same answers.

Third, the reconciliation guarantees are only as good as the workflow pinning. The README explicitly warns against a branch or movable tag. A team that pins to `main` gets whatever the upstream action does that day, and the attestation story weakens. Similarly, the evidence packet deliberately refuses to scan the whole repository, which means a claim whose anchors are not among the selected versions simply will not be verified. That is a defensible design, but it is a boundary, not a bug.

Finally, the README does not document rollback or uninstall. If you install Greplica into a repository and later want the hooks and binding gone, there is no command for that in the documentation.

## AGENTS.md and the alternative it replaces

package.json describes Greplica as a long-term, searchable AGENTS.md for coding agents. That is the clearest statement of the alternative: a hand-maintained AGENTS.md or CLAUDE.md file checked into the repository.

The difference in approach is retrieval. A markdown context file is loaded, in full or in part, every session, and it is edited by humans. Greplica explores repo structure, code and session transcripts, stores the result in a queryable memory, and answers a specific question such as how authentication works. A static file cannot answer a question it was not written to answer, and it drifts silently as code changes. Greplica's reconcile workflow exists precisely because the memory can drift too, but it at least attempts to prove that a stored claim still matches the code at a specific commit.

The trade is operational weight. A markdown file needs no Node.js version, no SQLite store, no GitHub OIDC permissions and no hourly schedule. Greplica needs all of those in managed mode. For a small repository with a stable architecture, the markdown file is probably the better choice.

## Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-30. Releases are frequent and small: v0.2.1 on 2026-07-22, v0.2.0 on 2026-07-21, and v0.1.51 on 2026-06-30. The 0.2.x line is where managed mode and shared memory arrive, and the README states that managed mode requires 0.2.0 or later, so anyone on 0.1.x is on a different feature set.

The licence is MIT, declared in both LICENSE and package.json. MIT is permissive: it allows use, modification and redistribution with the copyright notice and without warranty. That is a statement about the licence text, not advice about your situation; if you are folding Greplica into a product, read the licence yourself.

Upgrade cost concentrates in the managed path. The reusable workflow must be pinned to a full 40-character commit SHA, and the README notes that older servers retain the prior attestation shape. That means a server upgrade and a workflow pin bump can be coupled. The package also enforces a Node.js range at install time through `scripts/check-node-version.js`, so an environment on Node.js 20 will fail before anything else runs. The test script in package.json is a long chain of individual check scripts, which tells you the maintainers rely on many narrow assertions rather than a single broad suite; a failing check names one behaviour.

## Conclusion

Adopt Greplica if your agent sessions repeatedly rebuild the same repository context and you are willing to run Node.js 22 to 26 and keep a local SQLite store per repository. Skip it if you want a hosted service with no CLI, or if your code cannot leave your machine and you also need cross-clone sharing: managed mode keeps graph data on a server. Before rolling it out, verify three things: that `greplica install` produces the binding you expect for your platform, that `greplica graph context` returns useful answers on a subsystem you already know well, and, for managed mode, which commit SHA you pin the reusable reconcile workflow to, since the README says not to use a branch or movable tag.

## FAQ

### What Node.js version does Greplica need?

The README states Greplica requires Node.js 22 to 26, and package.json declares an engines range of >=22.0.0 <27.0.0 with a preinstall version check. An install on an unsupported version fails at that check.

### Does Greplica store my code on a server?

In local mode it stays fully local with no telemetry, and local SQLite holds the data. In managed mode the managed graph data stays on the server, while local SQLite stores only the repository binding, role cache, hook policy and runtime session metadata.

### How do I install Greplica for a repository?

The README recommends pasting an install prompt into your coding agent from inside the repository, pointing at docs/agent-install-prompt.md. That prompt runs a setup questionnaire and installs Greplica in local or managed mode.

### Can several contributors share the same Greplica memory?

Yes, through managed mode, which requires Greplica 0.2.0 or later and access to a managed Greplica server. Contributors on different clones and forks query the same repository memory, and an admin can create a reusable repository-scoped invite link that works for multiple GitHub users until it is revoked.

## Sources

- [Autoloops/greplica on GitHub](https://github.com/Autoloops/greplica)
- [License: MIT](https://github.com/Autoloops/greplica/blob/main/LICENSE)
- [Project website](https://autoloops.ai/greplica)
- [README](https://github.com/Autoloops/greplica/blob/main/README.md)
- [Releases](https://github.com/Autoloops/greplica/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/autoloops-greplica