Skip to main content
Glama
CosmonautJones

JacBrain

by CosmonautJones
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

JacBrain

A project memory for AI agents building with Jac.

Keep useful knowledge. Find what matters. Check it with the compiler.

Checks License: MIT

Try it · How it works · Roadmap

The idea

An AI coding agent often has to look up the same language rules and work through the same errors across sessions. JacBrain gives it a place to keep and find that knowledge.

It connects notes, code, compiler errors, and candidate fixes in a knowledge graph: a collection of records linked by how they relate. When an agent starts a task, JacBrain returns a small selection of relevant records for that project and Jac version.

The goal is to build effectively with Jac using less repeated explanation and fewer reference tokens. JacBrain supplies reusable language knowledge even when an agent does not reliably know Jac. It does not retrain the agent.

Related MCP server: @okfshare/mcp

How it works

flowchart LR
    A[Save notes and code] --> B[Find context for a task]
    B --> C[Agent proposes code]
    C --> D[Jac compiler checks it]
    D --> E[Keep the result]
    E --> B

For example, an agent working on an offer-search walker can ask for related notes and code. JacBrain returns matching records with their sources. The agent can then submit a candidate snippet to the real Jac compiler and keep the result for later retrieval.

A compiler pass means the snippet compiles. Tests are still needed to show that it behaves correctly.

Try it

You need Python 3.11+. This first example needs no Jac installation, API key, or extra Python packages. These commands work in PowerShell or Bash:

git clone https://github.com/CosmonautJones/jacbrain.git
cd jacbrain

# Save a sample note and code file
python -m jacbrain ingest examples/walker-note.md --project demo
python -m jacbrain ingest examples/walker-pattern.jac --project demo

# Ask for relevant context
python -m jacbrain context "walker Offer traversal" --project demo

You’ll get JSON containing matching records, their sources, and validation status. Data stays in .jacbrain/brain.sqlite3 on your machine. Choose only nonsecret files to ingest.

Next: connect a coding agent and enable compiler checks →

Load Jac's actual reference guides

With Jac 0.37.23 available, import its bundled knowledge once:

python -m jacbrain sync-guides
python -m jacbrain context "walker with one typed report after traversal" --project my-app

This imports the installed guides, splits them into source-linked sections, and connects their explicit references. Task queries can then use that language knowledge alongside your project's notes. Re-run the import to refresh it. See the Windows setup if Jac runs in WSL.

Where it stands

Early working foundation. You can use the local tools today; the complete learning loop is still being built.

Working today

Still to build

Import versioned Jac guides and save project evidence locally

Extract project relationships with Jac’s compiler

Retrieve context by task, project, and Jac version

Connect the native Jac graph to persistent storage

Check snippets through Jac MCP and save the results

Verify fixes against full projects and behavioral tests

Use the CLI, MCP interface, and separate Jac graph demo

Measure broader tasks, repairs, and graph-specific value

The persistent service currently uses Python and SQLite. The Jac nodes, edges, and walkers form a separate runnable graph model. “Learning” here means keeping evidence across sessions, not training an AI model.

First measured result

In a four-task pilot, selected context used 73% fewer reference tokens than curated complete guides. Both approaches passed all four compiler and behavior checks. Total observed model input fell by 16%, including tool overhead.

That is an encouraging small result, not proof of general savings. Graph and plain section retrieval returned identical context, so the graph itself has not yet shown an advantage. Read the experiment and its limits →

Explore further

I want to…

Start here

Connect my agent or check code

Setup guide

Understand the design

Architecture

Run the native Jac graph

Graph demo

See the API and data format

Interfaces · Schema

See what was tested

Verification

Contribute or troubleshoot

Development guide

Jac already provides MCP tools and code-context queries. JacBrain builds on that work and explores memory across tasks. Our prior-art review covers related projects and the questions we still need to test.

Built by Travis Jones, inspired by working with Jac on the M-Local team project. Independent of the Jac/Jaseci maintainers. MIT licensed.

Available Tools

3 tools
contextB

Return task context from project memory and installed Jac guides, scoped to exact Jac version.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
projectYes
max_bytesNo
jac_versionYes
expand_graphNo
include_guidesNo

TDQS

B3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It adds useful context by naming the data sources ('project memory and installed Jac guides') and the version-scoping constraint, but it does not disclose read-only safety, error behavior on version mismatch, rate limits, or how the output is composed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no wasted words. It states the action, the sources, and the scoping condition efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters, 3 required, no annotations, no output schema, and 0% schema description coverage, the description is too thin. It covers the high-level purpose but omits usage guidance, parameter meanings, output expectations, and behavioral details needed to invoke it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the schema does not document any of the 6 parameters. The one-sentence description only implicitly touches a few parameters ('task context' → task, 'project memory' → project, 'Jac guides' → include_guides, 'exact Jac version' → jac_version) and says nothing about max_bytes or expand_graph, leaving most parameter semantics unexplained.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description provides a specific verb ('Return') and resource ('task context from project memory and installed Jac guides'), plus a scope constraint ('scoped to exact Jac version'). It is clear what the tool does, but it does not differentiate itself from the sibling tools 'ingest' and 'validate'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no explicit when-to-use guidance, no prerequisites, and no mention of alternatives. An agent must infer that this retrieval tool should be called before working on a task, but nothing in the text states when to use it versus 'ingest' or 'validate'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ingestC

Ingest one explicitly selected local Markdown/text/Jac file.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
projectYes
jac_versionYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It conveys single-file scope but says nothing about side effects: where ingested content goes, whether re-ingesting overwrites, what permissions are needed, or what happens on failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single tight sentence with the key scoping constraint (one file, local, explicitly selected) front-loaded and no filler. It is efficient, though it is under-specified rather than over-verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Three required parameters with zero schema documentation, no annotations, and no output schema means the description is the only source of information and it omits nearly everything. An agent cannot reliably form a correct call from this alone.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for three required parameters. The description's "local" hints that path is a filesystem path, but project and jac_version are left entirely unexplained in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Ingest one explicitly selected local Markdown/text/Jac file" names a verb and a resource, and the word "explicitly" hints at a deliberate user action. However, "ingest" is opaque about what actually happens to the file, and nothing distinguishes it from the sibling tools context and validate.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to use this tool versus context or validate, nor any prerequisite or sequencing guidance. The phrase "explicitly selected" implies the caller must already have chosen a file, but that is inference, not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

validateC

Compile trusted candidate source through real Jac MCP; not runtime testing or sandboxing.

ParametersJSON Schema
NameRequiredDescriptionDefault
identityYes

TDQS

C2.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden. It says the operation compiles rather than tests, but discloses nothing about side effects, whether artifacts/state are written, permission requirements, or what a successful or failed result looks like.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is a single short sentence with no padding, so there is no waste. But it reads as a terse fragment whose meaning depends on Jac-specific jargon rather than being front-loaded with usable information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No annotations, no output schema, and an undocumented required parameter leave the agent short of what it needs to invoke this correctly. The description would need to carry behavior and parameter semantics itself and does not.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% and the single parameter "identity" is entirely undocumented. The description adds no meaning to it — it is unclear whether identity is a source path, module name, or handle — so it fails to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a verb and resource ("Compile trusted candidate source") and explicitly rules out runtime testing/sandboxing, which separates it from a test-runner. However "through real Jac MCP" and "trusted candidate source" are opaque, and it never says how it differs from siblings context/ingest.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives one negative boundary — "not runtime testing or sandboxing" — which rules out a plausible misuse. It offers no positive when-to-use condition, no prerequisites, and names no alternative tool the agent should pick instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedcontext
    • First observedingest
    • First observedvalidate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3/5.0

Scored across 3 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: context retrieves task context, ingest loads a file, and validate compiles source. There is no overlapping action or resource, and the descriptions reinforce the separation.

Naming Consistency3/5

All tool names are single lowercase words, but 'context' is a noun while 'ingest' and 'validate' are verbs, creating a mixed convention. It is readable but not a consistent verb_noun pattern.

Tool Count4/5

Three tools is lean but each covers a distinct stage in the Jac memory and validation workflow. The set is well-scoped, though slightly under the typical 3-15 range for a domain with potential CRUD operations.

Completeness3/5

The surface covers retrieval, ingestion, and validation, but lacks update/delete/forget or listing operations for project memory. Ingest also handles only one explicitly selected file, leaving notable lifecycle gaps.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers